NGLVieweR - Visualize and interact with Protein Data Bank (PDB) files in R
Click here to view a Shiny application integrating most features of NGLVieweR.
Description
NGLvieweR provides an R interface to the NGL.js JavaScript library. It can be used to visualize and interact with protein data bank files (PDB) in R and Shiny applications. It includes a set of API functions to manipulate the viewer after creation and makes it possible to retrieve data from the visualization into R.
Installation
NGLVieweR is available through GitHub
install.packages("remotes")
remotes::install_github("nvelden/NGLVieweR")Basics
You can load a PDB file directly or use a PDB code of a structure on RCSB.org. The below minimal example loads the PDB file and displays the structure in a “cartoon” representation.
#Load local pdb file
NGLVieweR("C:/7CID.pdb") %>%
addRepresentation("cartoon")
#Load protein by PDB code
NGLVieweR("7CID") %>%
addRepresentation("cartoon")
Functions
There are several functions to manipulate the viewer: - Hello - Test
You can view a “basic” NGLVieweR Shiny application by running the below code. Use “API” for an example using API calls or any of the function names (e.g “addSelection”") for function specific examples.
library(NGLVieweR)
library(shiny)
NGLVieweR_example("basic") Representations
You can load the structure as a “cartoon”, “ball+stick”, “line”, “surface”, “ribbon”, or any other representation listed in the NGL.js manual under “StructureRepresentation”. Multiple representations of the same structure can be overlaid by chaining the addSelection() function. Also see the “structure” tab in the demo app for a list of possible representations.
NGLVieweR("7CID") %>%
addRepresentation("cartoon") %>%
addRepresentation("ball+stick")
You can alter the appearance of select residues using the param argument. For a full list of options see the NGL.js “RepresentationParameters” and the “Selection language” section.
NGLVieweR("7CID") %>%
addRepresentation("cartoon", param=list(colorScheme = "residueindex")) %>%
addRepresentation("ball+stick", param=list(sele="233-248",
colorValue="red",
colorScheme="element")) %>%
addRepresentation("surface", param=list(colorValue = "white",
opacity=0.1))
Stage
You can alter the background color or set the zoom or rotation speed using the stageParameters() function. For a full list of options, see the “StageParameters” method in the official NGL.js manual. Note: Changes in background color are not visible in the RStudio viewer.
NGLVieweR("7CID") %>%
stageParameters(backgroundColor = "white", zoomSpeed = 1) %>%
addRepresentation("cartoon", param = list(name = "cartoon", colorScheme="residueindex"))
Labels
Labels can be addded by setting the addRepresentation() type parameter to “label”. For a full list of of options, see the LabelRepresentationParameters section in the NGL.js manual. Also see the “label” tab in the demo app for possible label settings.
NGLVieweR("7CID") %>%
addRepresentation("cartoon") %>%
addRepresentation("ball+stick", param=list(colorScheme = "element",
colorValue = "yellow",
sele = "20")) %>%
addRepresentation("label", param=list(sele="20",
labelType="format",
labelFormat='[%(resname)s]%(resno)s', #or enter custom text
labelGrouping="residue", #or "atom" (eg. sele = "20:A.CB")
color="white",
fontFamiliy="sans-serif",
xOffset = 1,
yOffset = 0,
zOffset = 0,
fixedSize = TRUE,
radiusType = 1,
radiusSize = 1.5, #Label size
showBackground=FALSE
#backgroundColor="black",
#backgroundOpacity=0.5,)
)
Zoom
You can zoom into specific residues using the ZoomMove() function.
NGLVieweR("7CID") %>%
addRepresentation("cartoon") %>%
addRepresentation("ball+stick", param=list(colorScheme = "element",
colorValue = "yellow",
sele = "20")) %>%
addRepresentation("label", param=list(sele="20",
labelType="format",
labelFormat='[%(resname)s]%(resno)s', #or enter custom text
labelGrouping="residue", #or "atom" (eg. sele = "20:A.CB")
color="white",
xOffset = 1,
fixedSize = TRUE,
radiusType = 1,
radiusSize = 1.5) #Label size
) %>%
zoomMove(center = "20",
zoom = "20",
duration = 0, #animation time in ms
z_offSet = -20)
Shiny
The NGLVieweROutput() and renderNGLVieweR() functions enable you to visualize PDB files within Shiny applications. See the NGLVieweR_example("basic") and “API” for live examples.
library(shiny)
library(NGLVieweR)
ui = fluidPage(NGLVieweROutput("structure"))
server = function(input, output) {
output$structure <- renderNGLVieweR({
NGLVieweR("7CID") %>%
addRepresentation("cartoon", param = list(name = "cartoon", color =
"residueindex")) %>%
addRepresentation("ball+stick",
param = list(
name = "cartoon",
sele = '1-20',
colorScheme = "element"
)) %>%
stageParameters(backgroundColor = "black") %>%
setQuality("high") %>%
setFocus(0) %>%
setSpin(TRUE)
})
}
shinyApp(ui, server)
API
In Shiny apps, you can manipulate the NGLVieweR widget after creation using specific “API” calls. You can for instance add or remove representations by refering to their name using the addSelection() or removeSelection() functions.
library(shiny)
library(NGLVieweR)
ui = fluidPage(
titlePanel("Viewer with API inputs"),
sidebarLayout(
sidebarPanel(
textInput("selection", "Selection", "1-20"),
selectInput("type", "Type", c("ball+stick", "cartoon", "backbone")),
selectInput("color", "Color", c("orange", "grey", "white")),
actionButton("add", "Add"),
actionButton("remove", "Remove")
),
mainPanel(
NGLVieweROutput("structure")
)
)
)
server = function(input, output) {
output$structure <- renderNGLVieweR({
NGLVieweR("7CID") %>%
addRepresentation("cartoon", param = list(name = "cartoon", colorScheme="residueindex")) %>%
stageParameters(backgroundColor = input$backgroundColor) %>%
setQuality("high") %>%
setFocus(0) %>%
setSpin(TRUE)
})
observeEvent(input$add, {
NGLVieweR_proxy("structure") %>%
addSelection(isolate(input$type),
param =
list(name="sel1",
sele=isolate(input$selection),
colorValue=isolate(input$color)))
})
observeEvent(input$remove, {
NGLVieweR_proxy("structure") %>%
removeSelection("sel1")
})
}
shinyApp(ui, server)
Possible API functions are:
addSelection()
removeSelection()
snapShot()
updateColor()
updateFocus()
updateFullscreen()
updateRepresentation()
updateRock()
updateSelection()
updateSpin()
updateStage()
updateVisibility()
updateZoomMove()